home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 January: Mac OS SDK / Dev.CD Jan 97 SDK2.toast / Development Kits (Disc 2) / OpenDoc / Developer Documentation / Recipes, Tech Notes & Articles / Recipes / Dynamic Binding / Binding and 'nmap' Recipe next >
Encoding:
Text File  |  1995-11-06  |  14.5 KB  |  357 lines  |  [TEXT/ttxt]
  1. OpenDoc™ Recipes
  2.  
  3.  
  4. Binding & nmap Recipe
  5. By The OpenDoc Design Team
  6.  
  7. © 1993-1995  Apple Computer, Inc. All Rights Reserved.
  8. Apple, the Apple logo, and Macintosh are registered trademarks of Apple Computer, Inc.
  9. Mac and OpenDoc are trademarks of Apple Computer, Inc.
  10.  
  11. Introduction
  12.  
  13. The OpenDoc Name Binding subsystem is responsible for determining what part editor or part viewer, of those installed on user's system,  is to be loaded in order to edit or view a given part or document.    The binding process uses information gathered from 'nmap' resources found in any installed editors or viewers.   Please see the OpenDoc Human Interface Guidelines for information on the installation of OpenDoc and of part editors.  This document decribes OpenDoc  'nmap' resources and provideds sample 'nmap' code.
  14.  
  15. Terms used and definitions
  16.  
  17. Kind - the Kind is a string (ISO Type format) which is used to identify a data format.  Examples of Kinds may be “SurfCorp:SurfText”, “SurfCorp:Picture:BlackAndWhite”, “ SurfCorp:Picture:Color”
  18.  
  19. Category - kinds can be grouped together in one or more categories. Examples of Categories: “OpenDoc:Category:Text”, “OpenDoc:Category:Graphics”, “OpenDoc:Category:Table”.  Kinds may be in more than one category.
  20.  
  21. Part Editor - a Part Editor is a dynamically linked library which has the ability to manipulate (read, Sample, edit, print, write) a number of different Kinds of Parts.  Since the context implies it, “editor” is often used instead of “part editor”.  An editor is said to exist, or to be, if it has been installed.
  22.  
  23. Part Viewer - a Part Viewer is a Part Editor which is not capable of changing the contents of Parts.
  24.  
  25. Binding - Binding is the act of taking a Part and assigning a Part Editor to it at run time.  Unbound - without a binding (to an Editor).
  26.  
  27. Fidelity - different Kinds of data can be said to represent the same information, but some may be qualitatively better or worse than others.  A qualitatively better Kind is said be of higher Fidelity.  There is no universal ordering of Kinds by Fidelity, therefore Fidelity is always determined by a particular context.  Part Editors support many different Kinds, and stored with the Part Editor is a list of those Kinds in Fidelity ordering  Parts may contain many different Kinds, different representations of their content, and they are Fidelity ordered by what the Part Editor which last wrote out that part considers Fidelity.
  28.  
  29. Editor ID - Is the System Objects Model (SOM) Class ID of a Part object.  Its format is simply <module>::<class name>.  The module and class name are defined in a part's .idl file.  The one for Editor Setup, for example, now looks like Apple::ODEditorSetup.
  30.  
  31. Viewer ID-the same as an EditorID, only for part viewers.
  32.  
  33. Recipe
  34.  
  35. In order for Binding to work, part-editors are required to contain structures that describe the Editor's ID and the Kind and Category of the data that the editor can edit.  On the Macintosh, these structures exist in the form of 'nmap' resources found in each Part Editor's shared library file.  These resources are used by OpenDoc to construct a set of look-up tables for this information  when a document is first opened.
  36.  
  37. Specifying a Part Editor'sSupported Kinds
  38.  
  39. Part editors are required by OpenDoc to contain an EditorKinds ‘nmap’.  It will need to contain a list of Editor IDs each followed by a list of kinds that are supported by that editor.  The kinds are to be listed in order of fidelity for an editor.   Please see the Multiple Kind Support Recipe for information on how an editor can support more than one kind and for information on fidelity ordering.  Notice that multiple editors could exist in one library, so that in this resource each editor would map to its list of kinds.  The table below shows what this list would look like. 
  40.  
  41. Editor        Kinds
  42. editorID1                            kind                            kind2                            …                            kindn
  43. editorID2                            …
  44. .
  45. .
  46. .                                                                                                            
  47. editorIDn                                …
  48.  
  49. Categorizing Each Kind
  50.  
  51. Part editors are also required by OpenDoc to contain an KindCategories ‘nmap’. Each kind that an editor supports belongs to a category.  The KindCategories ‘nmap’ contains a list of each kind followed by an unordered list of categories that the kind belongs to.   The table below shows what this list would look like.
  52.  
  53. Kind        Categories
  54. Kind1                            category 1                            category 2                                …                                        categoryn
  55. Kind2                            …
  56. .
  57. .
  58. .    
  59. kindn                                    …
  60.  
  61. Creating User-visible Strings
  62.  
  63. The next three tables illustrate the next three ‘nmap’ resources that part editors are required to contain.  They are used to map kind, category, and editor ID ISO strings to user-visible strings.  In the first table, each kind is mapped to a corresponding user-visible string.  The second and third tables illustrate similar mappings for categories and editor IDs.  It is IMPORTANT to note that it is not necessary to provide Category user strings for OpenDoc standard categories.  OpenDoc already provides these.
  64.  
  65. Kind        User String
  66. kind1                        kind1userstring
  67. kind2                        kind2userstring
  68. .
  69. .
  70. .    
  71. kindn                    kindnuserstring
  72.  
  73. Category    User String
  74. category1                        cateory1userstring
  75. category2                     cateory2userstring
  76. .
  77. .
  78. .    
  79. categoryn                        cateorynuserstring
  80.  
  81. Editor        User String
  82. editorID1                        editorID1userstring
  83. editorID2                        editorID2userstring
  84. .
  85. .
  86. .    
  87. editorIDn                        editorIDnuserstring
  88.  
  89.  
  90. Specifying Macintosh File Type Information
  91.  
  92. The last ‘nmap’ that is required for all part editors is the KindMacOSType ‘nmap’.  This table maps OpenDoc  kinds to Macintosh file types.  It will be used to determine the icon to be associated with each OpenDoc kind.  This table is not to be confused with the EditorPlatformKinds ‘nmap’ that will describe to OpenDoc which Standard Mac Kinds an editor can edit.  That ‘nmap’ is described later in this document.  The following table describes the KindMacOSType ‘nmap’.
  93.  
  94. Kind        OSType
  95. kind1                            OSType
  96. kind2                            OSType
  97. .
  98. .
  99. .    
  100. kindn                            OSType
  101.  
  102.  
  103. Supporting Standard Macintosh Data Types
  104.  
  105. The EditorPlatformKinds ‘nmap’ is only required by those part editors that have the capability to support any Standard Mac Kinds.  This ‘nmap’ will describe to OpenDoc which Standard Mac Kinds an editor can edit.  DO NOT include Standard Mac Kinds in your normal EditorKinds 'nmap' resource.
  106.  
  107. An OpenDoc Editor which ONLY supports standard Macintosh Kinds is a special case.  It should NOT contain the following 'nmap' resources described above:  Editor Kinds, Kind Categories, Kind User String, and Category User String.  
  108.  
  109. Please see the Multiple Kind Support Recipe for more information on how an editor can support Standard Mac Kind data.  
  110.  
  111. The EditorPlatformKinds ‘nmap’ will provide a list of PlatformTypeSpaces for every editor in the shared library.  A PlatformTypeSpace will contain four things:  a PlatformTypeSpace type (either file or data), the Macintosh file or data OSType, a user-string for the type, and the category that the type belongs to.  There are only two PlatformTypeSpace types, kODPlatformFileType and kODPlatformDataType indicating a file or a data type supported by the editor.  The following table describes the EditorPlatformKinds ‘nmap’.  
  112.  
  113. Editor                                                       PlatformTypeSpace                            OSType                            UserString                             Category
  114. editorID1                            fileOrData                                                                                                            ostype1              userString1                              category1
  115.                                                                                                                     fileOrData                                                                                                            ostype2              userString2                              category2
  116.                                                                                                                     fileOrData                                                                                                            ostypen                  userStringn                              category1n
  117. editorID2                            fileOrData                                                                                                            ostype1              userString1                              category1
  118.                                                                                                                     fileOrData                                                                                                            ostype2              userString2                              category2
  119.                                                                                                                     fileOrData                                                                                                            ostypen                  userStringn                              category1n
  120. .
  121. .
  122. .    
  123. editorIDn                            fileOrData                                                                                                            ostype1              userString1                              category1
  124.                                                                                                                     fileOrData                                                                                                            ostype2              userString2                              category2
  125.                                                                                                                     fileOrData                                                                                                            ostypen                  userStringn                              category1n
  126.  
  127.  
  128. Providing AppleGuide Support
  129.  
  130. In order for an Editor to provide AppleGuide support two things must be in place.  First, AppleGuide GuideFiles must be installed for each Editor in the same folder as the shared library that contains the Editor or set of Editors.  Second, the shared library  must include an 'nmap' resource that specifies the help file name or names.  The following table describes the help file 'nmap'.
  131.  
  132.  
  133. Editor                                                       Help File Name
  134. editorID1                            helpFileName1
  135. editorID2                            helpFileName2
  136. .
  137. .
  138. .    
  139. editorIDn                            helpFileNamen
  140.  
  141.  
  142. Part Viewers
  143.  
  144. Part Viewer libraries are required to include a additional ‘nmap’ resource indicating to OpenDoc that they are viewers and not regular part editors.  The PartViewers ‘nmap’ simply includes a list of viewerIDs  for each viewer in the library and their corresponding viewer types.  Currently, there is only one viewer type, kODSimpleViewer.   The following table describes the PartViewers ‘nmap’. 
  145.  
  146. Viewer    
  147. viewerID1                        kODSimpleViewer
  148. viewerID2                        kODSimpleViewer
  149. .
  150. .
  151. .    
  152. viewerIDn               kODSimpleViewer
  153.  
  154.  
  155. Container Suites
  156.  
  157. Container Suite libraries are only required to have one ‘nmap’, the ContainerSuite ‘nmap’.  This resource will contain a list of contianer types mapped with container suite class IDs. The following table describes the ContainerSuite ‘nmap’. 
  158.  
  159. Container Type                    Container Suite
  160. container Type1                containerSuiteID1        
  161. container Type2                containerSuiteID2
  162. .
  163. .
  164. .    
  165. contianer Typen            containerSuiteIDn
  166.  
  167. Coding Required
  168.  
  169. Six 'nmap' resources are required for each part-editor to describe each of the above name space tables.   The 'nmap' containing the Editor Kinds Supported data will also be an array of ISO String lists.   A sample resource definition looks like:
  170.  
  171. resource kODNameMappings (kSamplePartEditorKinds_nmapID) {
  172.     kODEditorKinds,                /* Name Space name */
  173.     {    /* array KeyList: 1 elements */
  174.             /* [1] */
  175.             kSamplePartID,            /* Part-editor class ID (SOM class ID) */
  176.             kODIsAnISOStringList {
  177.             /* array ValueList: 1 elements */
  178.             /* [1] */
  179.             {
  180.                 kODKindTestSample    /* Kind 1 */
  181.             }
  182.         }
  183.     }
  184. };
  185.  
  186. The 'nmap' containing the data for the Kind and Categories table will be an array of ISO String lists.  A sample resource definition looks like:
  187.  
  188. resource kODNameMappings (kSamplePartKindsCategories_nmapID) {
  189.     kODKind,                        /* Name Space name */
  190.     {    /* array KeyList: 1 elements */
  191.             /* [1] */
  192.             kODKindTestSample,            /* Kind 1 */
  193.             kODIsAnISOStringList {
  194.             /* array ValueList: 1 elements */
  195.             /* [1] */
  196.             {
  197.                 kODCategoryGraphics        /* Category 1 */
  198.             }
  199.         }
  200.     }
  201. };
  202.  
  203.  
  204. The next three ‘nmap’s, Kind user strings, Category user strings and Editor user strings, contain lists of mappings between internal ISO Strings and user-visible International Text strings.  Sample resources definitions looks like:
  205.  
  206. resource kODNameMappings (kSamplePartKindUserString_nmapID) {
  207.     kODKindUserString,                /* Name Space name */
  208.     {    /* array KeyList: 1 elements */
  209.          /* [1] */
  210.          kODKindTestSample,        /* Kind */
  211.          kODIsINTLText {        /* International String */
  212.                     smRoman,
  213.                     langEnglish,
  214.                     kSampleKindUserString
  215.         }
  216.     }
  217. };
  218.  
  219. resource kODNameMappings (kSamplePartCategoryUserString_nmapID) {
  220.     kODCategoryUserString,            /* Name Space name */
  221.     {    /* array KeyList: 1 elements */
  222.          /* [1] */
  223.          kODCategoryGraphics,        /* Category */
  224.          kODIsINTLText {        /* International String */
  225.                     smRoman,
  226.                     langEnglish,
  227.                     kSampleCategoryUserString
  228.         }
  229.     }
  230. };
  231.  
  232. resource kODNameMappings (kSamplePartEditorUserString_nmapID) {
  233.     kODEditorUserString,            /* Name Space name */
  234.     {    /* array KeyList: 1 elements */
  235.          /* [1] */
  236.          kSamplePartID,            /* Editor class ID (SOM class ID) */
  237.          kODIsINTLText {        /* International String */
  238.                     smRoman,
  239.                     langEnglish,
  240.                     kSampleEditorUserString
  241.         }
  242.     }
  243. };
  244.  
  245. The Old Macintosh OSType nmap contains a list of mappings between the new OpenDoc kind and the old Macintosh file type.  A sample resource definition looks like:
  246.  
  247. resource kODNameMappings (kSamplePartKindOldMacOSType_nmapID) {
  248.     kODKindOldMacOSType,        /* Name Space name */
  249.     {/* array KeyList: 1 elements */
  250.          /* [1] */
  251.          kODKindTestSample,        /* Kind */
  252.          kODIsMacOSType {
  253.                     kSampleOSType        /* 4 character OSType */
  254.         }
  255.     }
  256. };
  257.  
  258. The EditorPlatformKinds ‘nmap’ is only required by those editors that are capable of editing Standard Mac Kinds.  A sample EditorPlatformKinds nmap definition looks like:
  259.  
  260. resource kODNameMappings (kSamplePartEditorPlatformKinds_nmapID) {
  261.     kODEditorPlatformKind,
  262.     {    /* array KeyList: 1 elements */
  263.         /* [1] */
  264.         kSamplePartID,
  265.         kODIsPltfmTypeSpac {
  266.             /* array PltfmTypeSpacList: 4 elements */
  267.             {
  268.                 /* [1] */
  269.                 kODPlatformFileType, 
  270.                 kTEXTOSType, 
  271.                 smRoman, 
  272.                 langEnglish, 
  273.                 kDragKindUserString1, 
  274.                 kODCategoryPlainText,
  275.                 /* [2] */
  276.                 kODPlatformFileType, 
  277.                 kstxtOSType, 
  278.                 smRoman, 
  279.                 langEnglish, 
  280.                 kDragKindUserString2, 
  281.                 kODCategoryStyledText,
  282.                 /* [3] */
  283.                 kODPlatformDataType, 
  284.                 kTEXTOSType, 
  285.                 smRoman, 
  286.                 langEnglish, 
  287.                 kDragKindUserString3, 
  288.                 kODCategoryPlainText,
  289.                 /* [4] */
  290.                 kODPlatformDataType, 
  291.                 kstxtOSType, 
  292.                 smRoman, 
  293.                 langEnglish, 
  294.                 kDragKindUserString5, 
  295.                 kODCategoryStyledText
  296.             }
  297.         }
  298.     }
  299. };
  300.  
  301. The EditorPlatformKinds ‘nmap’ is only required by those editors that provide AppleGuide support.  A sample HelpFileName  nmap definition looks like:
  302.  
  303. resource kODNameMappings (kSamplePartHelpFileName_nmapID) {
  304.     kODEditorHelpFile,
  305.     {    /* array KeyList: 1 elements */
  306.         /* [1] */
  307.         kSamplePartID,
  308.         kODIsHelpFileName {
  309.                 kSamplePartHelpFileName
  310.         }
  311.     }
  312. };
  313.  
  314. The Viewers ‘nmap’ is only required by Viewers.  A sample Viewers nmap definition looks like:
  315.  
  316. resource kODNameMappings (kSampleViewer_nmapID) {
  317.     kODViewer,        /* Name Space name */
  318.     {/* array KeyList: 1 elements */
  319.          /* [1] */
  320.          kSampleViewerID                /* Viewer */
  321.          kODIsAnISOString {    
  322.                 kODSimpleViewer            /* Viewer Type */
  323.         }
  324.     }
  325. };
  326.  
  327. The ContainerSuite ‘nmap’ is only required by ContainerSuites.  A sample ContainerSuite ‘ nmap’ definition looks like:
  328.  
  329. resource kODNameMappings (kSampleContainerSuite_nmapID) {
  330.     kODContainerSuite,
  331.     {    /* array Types: 3 elements */
  332.         /* [1] */
  333.         kODSampleContainerFileContainer,
  334.         kODIsAnISOString {    
  335.                 kODFileContainerID
  336.         },
  337.         /* [2] */
  338.         kODSampleContainerMemoryContainer,
  339.         kODIsAnISOString {    
  340.                 kODMemoryContainerID
  341.         },
  342.         /* [3] */
  343.         kODSampleContainerEmbeddedContainer,
  344.         kODIsAnISOString {    
  345.                 kODEmbeddedContainerID
  346.         },
  347.         /* [4] */
  348.         kODSampleContainerUpdateContainer,
  349.         kODIsAnISOString {    
  350.                 kODUpdateContainerID
  351.         }
  352.     }
  353. };
  354.  
  355. The Type definition of the nmap resource can by found in the the file ODTypes.r.
  356.  
  357.